home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
SGI Freeware 2002 November
/
SGI Freeware 2002 November - Disc 2.iso
/
dist
/
fw_hylafax.idb
/
usr
/
freeware
/
catman
/
u_man
/
cat1
/
hylafax-client.Z
/
hylafax-client
Wrap
Text File
|
2002-07-08
|
24KB
|
491 lines
HYLAFAX-CLIENT(1) HYLAFAX-CLIENT(1)
NNAAMMEE
HylaFAX-client - introduction to _H_y_l_a_F_A_X client applica
tions and usage
SSYYNNOOPPSSIISS
sseennddffaaxx [_o_p_t_i_o_n_s] [_f_i_l_e_s...]
sseennddppaaggee [_o_p_t_i_o_n_s] [_m_e_s_s_a_g_e...]
ffaaxxssttaatt [_o_p_t_i_o_n_s]
ffaaxxrrmm [_o_p_t_i_o_n_s]
ffaaxxaalltteerr [_o_p_t_i_o_n_s] _j_o_b_i_d...
ffaaxx22ppss [_o_p_t_i_o_n_s] [_f_i_l_e_s...]
DDEESSCCRRIIPPTTIIOONN
_H_y_l_a_F_A_X is a telecommunication system for UNIX systems.
Among the features of _H_y_l_a_F_A_X are:
_H_y_l_a_F_A_X runs as a network service; this means a modem
may be effectively shared by a large number of users.
_H_y_l_a_F_A_X can be configured to work with a wide variety
of modems on a wide variety of systems.
Access to the system can be restricted by the adminis
trator to selected hosts and/or users.
Transmission requests may be processed immediately
(default) or queued for processing at a later time, in
the manner of the _a_t(1) command.
Remote facsimile machines may be polled to retrieve
publicly available documents.
POSTSCRIPT, PDF, and TIFF Class F documents are passed
directly to the fax server for transmission; the system
attempts to convert other file formats to either
POSTSCRIPT or TIFF through the use of an extensible
file typing and conversion facility. In normal opera
tion ASCII-text, _t_r_o_f_f(1) output, and Silicon Graphics
images are automatically converted. Additional file
formats can be added; see _t_y_p_e_r_u_l_e_s(${MANNUM4_5}).
The _f_a_x_c_o_v_e_r(1) program can be automatically invoked to
create a cover page for each facsimile, using informa
tion deduced by the _s_e_n_d_f_a_x command. Alternatively,
users may supply their own cover pages using their pre
ferred tools.
Facsimile are normally imaged in a system-default page
size (usually letter-size pages, 8.5" by 11", for sites
in North America). Alternate page sizes can be speci
fied with a --ss option to all _H_y_l_a_F_A_X programs. Well
known page sizes include: ISO A3, ISO A4, ISO A5, ISO
A6, ISO B4, North American Letter, American Legal,
American Ledger, American Executive, Japanese Letter,
and Japanese Legal. Note that it may not be permissi
ble to image into the full page area; the guaranteed
reproducible area for a page is typically smaller.
Also, note that while arbitrary page sizes can be spec
ified, only a limited number of page dimensions are
supported by the facsimile protocol. Thus if an odd-
size facsimile is submitted for transmission it may not
be possible to determine if it can be sent until the
fax server establishes communication with the remote
facsimile machine.
Facsimile can be sent at low resolution (98 lines/inch)
or medium resolution (196 lines/inch)--often called
_f_i_n_e _m_o_d_e. Documents with mixed resolution pages are
handled correctly.
Users are notified by electronic mail if a job can not
be transmitted. It is also possible to receive notifi
cation by mail when a job has been completed success
fully and each time that the job is requeued for
retransmission. Any untransmitted documents are
returned to the sender by electronic mail in a form
suitable for resubmission.
Support is provided for broadcasting facsimile. The
_H_y_l_a_F_A_X server software optimizes preparation of broad
cast documents and the client applications support the
notion of a _j_o_b _g_r_o_u_p which permits a group of jobs to
be manipulated together.
Support is provided for transmitting alpha-numeric mes
sages to pager devices or GSM mobiles using the Simple
Network Paging Protocol (SNPP) and the IXO or UCP pro
tocol (for message delivery).
The _H_y_l_a_F_A_X software is divided into two packages: soft
ware used on client machines and software used on machines
where one or more modems reside. Client software
includes:
_s_e_n_d_f_a_x, a program to submit outgoing facsimile;
_s_e_n_d_p_a_g_e, a program to submit alpha-numeric messages to
SNPP servers;
_f_a_x_s_t_a_t, a program obtain status information about
_H_y_l_a_F_A_X servers;
_f_a_x_r_m, a program to remove jobs and documents;
_f_a_x_a_l_t_e_r, a program to change parameters of queued
jobs; and
_f_a_x_2_p_s, a program that converts facsimile documents to
POSTSCRIPT so that they may be viewed with a POSTSCRIPT
previewer or printed on a POSTSCRIPT printer (this pro
gram is actually part of the companion TIFF distribu
tion that is used by _H_y_l_a_F_A_X).
Many systems also support submission of outgoing facsimile
by electronic mail and/or graphical interfaces to the
_s_e_n_d_f_a_x program. Such facilities are site-dependent; con
sult local documentation for more information.
GGEETTTTIINNGG SSTTAARRTTEEDD
To use the _H_y_l_a_F_A_X client software on your machine you
need to either load the appropriate software on your
machine, or you need to locate a machine that already has
the client software installed and setup symbolic links to
the appropriate directories. If you choose the latter,
then beware that you need links to three directories: the
directory where client applications reside, _$_{_B_I_N_}, the
directory where the client application database files
reside, _$_{_L_I_B_D_A_T_A_}, and the directory where document
conversion programs reside, _$_{_L_I_B_E_X_E_C_} (the last two
directories may be the same on your system).
Once the software is setup on your machine you need to
locate a host that has a facsimile server that you can
use. The host, and possibly the modem on the host, should
be defined in your environment in the FAXSERVER variable.
For example, for _c_s_h users,
setenv FAXSERVER flake.asd
or for _k_s_h or _s_h users,
FAXSERVER=flake.asd; export FAXSERVER
If there are multiple modems on your server then you may
be assigned to use a specific modem. For example, if you
are to use the modem attached to the _t_t_y_m_2 port on the
server machine, then the FAXSERVER variable should be
setup as
FAXSERVER=ttym2@flake.asd; export FAXSERVER
(Note: the SNPPSERVER environment variable is used instead
of FAXSERVER by the _s_e_n_d_p_a_g_e program; consult _s_e_n_d_
_p_a_g_e(${MANNUM1_8}) for more information.)
Note also, that before you can submit outgoing facsimile
jobs the administrator for the facsimile server may need
to register your identity in an access control list. You
will encounter the message ``_5_3_0 _U_s_e_r _%_s _a_c_c_e_s_s _d_e_n_i_e_d_.''
if access to your server is controlled and you are not
properly registered or you may be prompted for a password
and then denied service with ``_5_3_0 _L_o_g_i_n _i_n_c_o_r_r_e_c_t_.''.
DDIIAALL SSTTRRIINNGGSS
A dial string specifies how to dial the telephone in order
to reach a destination facsimile machine. _H_y_l_a_F_A_X permits
arbitrary strings to be passed to the facsimile server so
that users can specify credit card information, PBX rout
ing information, etc. Alphabetic characters are automati
cally mapped to their numeric key equivalents (e.g.
``1800GotMilk'' becomes ``18004686455''). Other charac
ters can be included for readability; anything that must
be stripped will be removed by the server before the dial
ing string is passed to the fax modem. Private informa
tion such as credit card access codes are withheld from
status messages and publicly accessible log files (with
proper configuration). Facsimile servers also automati
cally insert any leading dialing prefixing strings that
are required to place outgoing phone calls; e.g. dialing
``9'' to get an outside line. Additionally, if a phone
number is fully specified with the international direct
dialing digits (IDDD), then any prefixing long distance or
international dialing codes that are required to place the
call will be inserted in the dial string by the server.
For example, ``+31.77.594.131'' is a phone number in the
Netherlands; it would be converted to ``0113177594131'' if
the call is placed in the United States. The number
``+14159657824'' is a phone number in California; if this
number is called from within the 415 area code in the
United States, then the server would automatically convert
this to ``9657824'' because in the San Francisco Bay Area,
local phone calls must not include the area code and long
distance prefixing code.
The general rule in crafting dial strings is to specify
exactly what you would dial on your telephone; and, in
addition, the actual phone number can be specified in a
location-independent manner by using the IDD syntax of
``+_c_o_u_n_t_r_y_-_c_o_d_e _l_o_c_a_l_-_p_a_r_t''.
CCOOVVEERR PPAAGGEESS
The _s_e_n_d_f_a_x program can automatically generate a cover
page for each outgoing facsimile. Such cover pages are
actually created by the _f_a_x_c_o_v_e_r(1) program by using
information that is deduced by _s_e_n_d_f_a_x and information
that is supplied on the command line invocation of _s_e_n_d_
_f_a_x. Users may also request that _s_e_n_d_f_a_x not supply a
cover page and then provide their own cover page as part
of the data that is to be transmitted.
Automatically-generated cover pages may include the fol
lowing information:
the sender's name, affiliation, geographic location,
fax number, and voice telephone number;
the recipient's name, affiliation, geographic location,
fax number, and voice telephone number;
text explaining what this fax is ``regarding'';
text commentary;
the local date and time that the job was submitted;
the number of pages to be transmitted.
Certain of this information is currently obtained from a
user's personal facsimile database file; ~~//..ffaaxxddbb. Note
that this file is deprecated; it is described here only
because it is still supported for compatiblity with older
versions of the software.
The ..ffaaxxddbb file is an ASCII file with entries of the form
_k_e_y_w_o_r_d :: _v_a_l_u_e
where _k_e_y_w_o_r_d includes:
NNaammee a name associated with destination
fax machine;
CCoommppaannyy a company name;
LLooccaattiioonn in-company locational information,
e.g. a building#;
FFAAXX--NNuummbbeerr phone number of fax machine;
VVooiiccee--NNuummbbeerr voice telephone number.
Data is free format. Whitespace (blank, tab, newline) can
be freely interspersed with tokens. If tokens include
whitespace, they must be encloseed in quote marks (``"'').
The ``#'' character introduces a comment--everything to
the end of the line is discarded.
Entries are collected into aggregate records by enclosing
them in ``[]''. Records can be nested to create a hierar
chy that that supports the inheritance of information--
unspecified information is inherited from parent aggregate
records.
For example, a sample file might be:
[ Company: "Silicon Graphics, Inc."
Location: "Mountain View, California"
[ Name: "Sam Leffler" FAX-Number: +1.415.965.7824 ]
]
which could be extended to include another person at Sili
con Graphics with the following:
[ Company: "Silicon Graphics, Inc."
Location: "Mountain View, California"
[ Name: "Sam Leffler" FAX-Number: +1.415.965.7824 ]
[ Name: "Paul Haeberli" FAX-Number: +1.415.965.7824 ]
]
Experience indicates that the hierarchical nature of this
database format makes it difficult to maintain with auto
mated mechanisms. As a result it is being replaced by
other, more straightforward databases that are managed by
programs that front-end the _s_e_n_d_f_a_x program.
CCOONNFFIIGGUURRAATTIIOONN FFIILLEESS
_H_y_l_a_F_A_X client applications can be tailored on a per-user
and per-site basis through configuration files. Per-site
controls are placed in the file $${{LLIIBBDDAATTAA}}//hhyyllaa..ccoonnff,
while per-user controls go in ~~//..hhyyllaarrcc. In addition a
few programs that have many parameters that are specific
to their operation support an additional configuration
file; these files are identified in their manual pages.
Configuration files have a simple format and are entirely
ASCII. A configuration parameter is of the form
ttaagg: _v_a_l_u_e
where a _t_a_g identifies a parameter and a _v_a_l_u_e is either a
string, number, or boolean value. Comments are introduced
by the ``#'' character and extend to the end of the line.
String values start at the first non-blank character after
the ``:'' and continue to the first non-whitespace charac
ter or, if whitespace is to be included, may be enclosed
in quote marks (``"''). String values enclosed in quote
marks may also use the standard C programming conventions
for specifying escape codes; e.g. ``\n'' for a newline
character and ``\xxx'' for an octal value. Numeric values
are specified according to the C programming conventions
(leading ``0x'' for hex, leading ``0'' for octal, other
wise decimal). Boolean values are case insensitive. For
a true value, either ``Yes'' or ``On'' should be used.
For a false value, use ``No'' or ``Off''.
RREECCEEIIVVEEDD FFAACCSSIIMMIILLEE
Incoming facsimile are received by facsimile servers and
deposited in a receive queue directory on the server
machine. Depending on the server's configuration, files
in this directory may or may not be readable by normal
users. The _f_a_x_s_t_a_t program can be used to view the con
tents of the receive queue directory:
hyla% faxstat -r
HylaFAX scheduler on hyla.chez.sgi.com: Running
Modem ttyf2 (+1 510 999-0123): Running and idle
Protect Page Owner Sender/TSI Recvd@ Filename
-rw-r-- 9 fax 1 510 5268781 05Jan96 fax00005.tif
-rw-r-- 8 fax 1 510 5268781 07Jan96 fax00009.tif
-rw-r-- 2 fax 1 510 5268781 07Jan96 fax00010.tif
-rw-r-- 3 fax +14159657824 08Jan96 fax00011.tif
-rw-r-- 2 fax +14159657824 08Jan96 fax00012.tif
Consult the _f_a_x_s_t_a_t manual page for a more detailed
description of this information.
Received facsimile are stored as TIFF Class F files.
These files are bilevel images that are encoded using the
CCITT T.4 or CCITT T.6 encoding algorithms. The _f_a_x_2_p_s(1)
program can be used to view and print these files. A file
can be viewed by converting it to POSTSCRIPT and then
viewing it with a suitable POSTSCRIPT previewing program,
such as _x_p_s_v_i_e_w(1) (Adobe's Display POSTSCRIPT-based
viewer), _g_h_o_s_t_v_i_e_w(1) (a public domain previewer), or
image viewer programs such as _v_i_e_w_f_a_x(1) (public domain),
_f_a_x_v_i_e_w(1) (another public domain TIFF viewer program),
_x_v(1) (shareware and/or public domain), or _x_t_i_f_f(1) (a
program included in the public domain TIFF software dis
tribution). Consult your local resources to figure out
what tools are available for viewing and printing received
facsimile.
CCLLIIEENNTT--SSEERRVVEERR PPRROOTTOOCCOOLL
_H_y_l_a_F_A_X client applications communicate with servers using
either a special-purpose _c_o_m_m_u_n_i_c_a_t_i_o_n_s _p_r_o_t_o_c_o_l that is
modeled after the Internet File Transfer Protocol (FTP)
or, when submitting alpha-numeric pages, the Simple Net
work Paging Protocol (SNPP), specified in RFC 1861. All
client programs support a --vv option that can be used to
observe the protocol message exchanges. In some situa
tions it may be more effective to communicate directly
with a _H_y_l_a_F_A_X server using the client-server protocol.
This can be accomplished with an FTP or Telnet client
application; though an FTP client is recommended because
it implements the protocol needed to obtain server status
information. For information on the server-side support
provided with _H_y_l_a_F_A_X consult _h_f_a_x_d(${MANNUM1_8}). For
documentation on the client-server fax protocol consult
RFC XXXX (_t_o _b_e _f_i_l_l_e_d _i_n).
EEXXAAMMPPLLEESS
This section gives several examples of command line usage;
consult the manual pages for the individual commands for
information on the options and program operation.
The following command queues the file zzaallll..ppss for trans
mission to John Doe at the number (123)456-7890 using fine
mode; the server will attempt to send it at 4:30 A.M.:
sendfax -a "0430" -m -d "John Doe@1.123.456.7890"
zall.ps
(the leading ``1.'' is supplied to dial area code ``123''
in the United States.)
The following command generates a one-page facsimile that
is just a cover page:
faxcover -t "John Doe" -n "(123)456-7890"
-c "Sorry John, I forgot the meeting..." |
sendfax -n -d "(123)456-7890"
(note that the line was broken into several lines solely
for presentation.)
The following command displays the status of the facsimile
server and any jobs queued for transmission:
faxstat -s
The following command displays the status of the facsimile
server and any documents waiting in the receive queue on
the server machine:
faxstat -r
The following command shows how to use an FTP client pro
gram to communicate directly with a _H_y_l_a_F_A_X server:
hyla% ffttpp llooccaallhhoosstt hhyyllaaffaaxx
Connected to localhost.
220 hyla.chez.sgi.com server (HylaFAX (tm) Version 4.0beta005) ready.
Name (localhost:sam):
230 User sam logged in.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> ddiirr sseennddqq
200 PORT command successful.
150 Opening new data connection for "sendq".
208 126 S sam 5268781 0:3 1:12 16:54 No local dialtone
226 Transfer complete.
ftp> qquuoottee jjkkiillll 220088
200 Job 208 killed.
ftp> ddiirr ddoonneeqq
200 PORT command successful.
150 Opening new data connection for "doneq".
208 126 D sam 5268781 0:3 1:12 No local dialtone
226 Transfer complete.
ftp> qquuoottee jjddeellee 220088
200 Job 208 deleted; current job: (default).
ftp> ddiirr ddooccqq
200 PORT command successful.
150 Opening new data connection for "docq".
-rw---- 1 sam 11093 Jan 21 16:48 doc9.ps
226 Transfer complete.
ftp> ddeellee ddooccqq//ddoocc99..ppss
250 DELE command successful.
ftp> ddiirr rreeccvvqq
200 PORT command successful.
150 Opening new data connection for "recvq".
-rw-r-- 4 fax 1 510 5268781 30Sep95 faxAAAa006uh
-rw-r-- 9 fax +14159657824 11Nov95 faxAAAa006nC
-rw---- 25 fax +14159657824 Fri08PM fax00016.tif
226 Transfer complete.
ftp> qquuiitt
221 Goodbye.
The following command shows how to use a Telnet client
program to communicate directly with an SNPP server:
hyla% tteellnneett mmeellaannggee..eessdd 444444
Trying 192.111.25.40...
Connected to melange.esd.sgi.com.
Escape character is '^]'.
220 melange.esd.sgi.com SNPP server (HylaFAX (tm) Version 4.0beta010) ready.
llooggiinn ssaamm
230 User sam logged in.
hheellpp
214 The following commands are recognized (* =>'s unimplemented).
214 2WAY* ALER* DATA HOLD LOGI MSTA* PING RTYP* STAT
214 ABOR CALL* EXPT* KTAG* MCRE* NOQU* QUIT SEND SUBJ
214 ACKR* COVE* HELP LEVE MESS PAGE RESE SITE
250 Direct comments to FaxMaster@melange.esd.sgi.com.
ppaaggee 55555511221122
250 Pager ID accepted; provider: 1800SkyTel pin: 5551212 jobid: 276.
sseenndd
250 Message processing completed.
qquuiitt
221 Goodbye.
Connection closed by foreign host.
FFIILLEESS
${BIN}/sendfax for sending facsimile
${BIN}/sendpage for sending alpha-numeric pages
${BIN}/fax2ps for converting facsimile to POSTSCRIPT
${BIN}/faxalter for altering queued jobs
${BIN}/faxcover for generating cover sheets
${BIN}/faxmail for converting email to POSTSCRIPT
${BIN}/faxrm for removing queued jobs
${BIN}/faxstat for facsimile server status
${LIBEXEC}/sgi2fax SGI image file converter
${LIBEXEC}/textfmt ASCII text converter
${LIBDATA}/typerules file type and conversion rules
${LIBDATA}/pagesizes page size database
${LIBDATA}/faxcover.ps prototype cover page
${LIBDATA}/dialrules optional client dialstring rules
${SPOOL}/tmp/sndfaxXXXXXX temporary files
SSEEEE AALLSSOO
_a_t(1), _f_a_x_2_p_s(1), _f_a_x_a_l_t_e_r(1), _f_a_x_c_o_v_e_r(1), _f_a_x_m_a_i_l(1),
_f_a_x_r_m(1), _f_a_x_s_t_a_t(1), _s_g_i_2_f_a_x(1), _f_a_x_q(${MANNUM1_8}),
_v_i_e_w_f_a_x(1), _h_y_l_a_f_a_x_-_s_e_r_v_e_r(${MANNUM4_5}), _d_i_a_l_r_u_l_e_s(${MAN
NUM4_5}), _p_a_g_e_s_i_z_e_s(${MANNUM4_5}), _t_y_p_e_r_u_l_e_s(${MAN
NUM4_5}), _s_e_r_v_i_c_e_s(4)
May 8, 1996 HYLAFAX-CLIENT(1)